home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2001 May / SGI Freeware 2001 May - Disc 3.iso / dist / fw_openssl.idb / usr / freeware / catman / p_man / cat3 / RSA_get_ex_new_index.Z / RSA_get_ex_new_index
Text File  |  2001-01-10  |  10KB  |  199 lines
  1.  
  2.  
  3.  
  4.      RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx((((3333))))11117777////SSSSeeeepppp////2222000000000000    ((((0000....9999....6666))))RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       RSA_get_ex_new_index,    RSA_set_ex_data, RSA_get_ex_data - add
  10.       application specific data to RSA structures
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.        #include <openssl/rsa.h>
  14.  
  15.        int RSA_get_ex_new_index(long argl, void *argp,
  16.               CRYPTO_EX_new    *new_func,
  17.               CRYPTO_EX_dup    *dup_func,
  18.               CRYPTO_EX_free *free_func);
  19.  
  20.        int RSA_set_ex_data(RSA *r, int idx,    void *arg);
  21.  
  22.        void    *RSA_get_ex_data(RSA *r, int idx);
  23.  
  24.        typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA    *ad,
  25.               int idx, long    argl, void *argp);
  26.        typedef void    free_func(void *parent,    void *ptr, CRYPTO_EX_DATA *ad,
  27.               int idx, long    argl, void *argp);
  28.        typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
  29.               int idx, long    argl, void *argp);
  30.  
  31.  
  32.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  33.       Several OpenSSL structures can have application specific
  34.       data attached    to them.  This has several potential uses, it
  35.       can be used to cache data associated with a structure    (for
  36.       example the hash of some part    of the structure) or some
  37.       additional data (for example a handle    to the data in an
  38.       external library).
  39.  
  40.       Since    the application    data can be anything at    all it is
  41.       passed and retrieved as a vvvvooooiiiidddd **** type.
  42.  
  43.       The RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx(((()))) function is initially called to
  44.       "register" some new application specific data. It takes
  45.       three    optional function pointers which are called when the
  46.       parent structure (in this case an RSA    structure) is
  47.       initially created, when it is    copied and when    it is freed
  48.       up. If any or    all of these function pointer arguments    are
  49.       not used they    should be set to NULL. The precise manner in
  50.       which    these function pointers    are called is described    in
  51.       more detail below. RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx(((()))) also takes
  52.       additional long and pointer parameters which will be passed
  53.       to the supplied functions but    which otherwise    have no
  54.       special meaning. It returns an iiiinnnnddddeeeexxxx which should be stored
  55.       (typically in    a static variable) and passed used in the iiiiddddxxxx
  56.       parameter in the remaining functions.    Each successful    call
  57.       to RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx(((()))) will return    an index greater than
  58.       any previously returned, this    is important because the
  59.       optional functions are called    in order of increasing index
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 11/10/00)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx((((3333))))11117777////SSSSeeeepppp////2222000000000000    ((((0000....9999....6666))))RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx((((3333))))
  71.  
  72.  
  73.  
  74.       value.
  75.  
  76.       RRRRSSSSAAAA____sssseeeetttt____eeeexxxx____ddddaaaattttaaaa(((()))) is used to set application specific    data,
  77.       the data is supplied in the aaaarrrrgggg parameter and    its precise
  78.       meaning is up    to the application.
  79.  
  80.       RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____ddddaaaattttaaaa(((()))) is used to retrieve    application specific
  81.       data.    The data is returned to    the application, this will be
  82.       the same value as supplied to    a previous RRRRSSSSAAAA____sssseeeetttt____eeeexxxx____ddddaaaattttaaaa(((())))
  83.       call.
  84.  
  85.       nnnneeeewwww____ffffuuuunnnncccc(((()))) is    called when a structure    is initially allocated
  86.       (for example with RRRRSSSSAAAA____nnnneeeewwww(((()))). The parent structure members
  87.       will not have    any meaningful values at this point. This
  88.       function will    typically be used to allocate any application
  89.       specific structure.
  90.  
  91.       ffffrrrreeeeeeee____ffffuuuunnnncccc(((()))) is called    when a structure is being freed    up.
  92.       The dynamic parent structure members should not be accessed
  93.       because they will be freed up    when this function is called.
  94.  
  95.       nnnneeeewwww____ffffuuuunnnncccc(((()))) and ffffrrrreeeeeeee____ffffuuuunnnncccc(((()))) take the same parameters. ppppaaaarrrreeeennnntttt
  96.       is a pointer to the parent RSA structure. ppppttttrrrr    is a the
  97.       application specific data (this wont be of much use in
  98.       nnnneeeewwww____ffffuuuunnnncccc(((()))). aaaadddd is a pointer to the CCCCRRRRYYYYPPPPTTTTOOOO____EEEEXXXX____DDDDAAAATTTTAAAA structure
  99.       from the parent RSA structure: the functions
  100.       CCCCRRRRYYYYPPPPTTTTOOOO____ggggeeeetttt____eeeexxxx____ddddaaaattttaaaa(((()))) and CCCCRRRRYYYYPPPPTTTTOOOO____sssseeeetttt____eeeexxxx____ddddaaaattttaaaa(((())))    can be called
  101.       to manipulate    it. The    iiiiddddxxxx parameter is the index: this will
  102.       be the same value returned by    RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx(((()))) when
  103.       the functions    were initially registered. Finally the aaaarrrrggggllll
  104.       and aaaarrrrggggpppp parameters are the values originally    passed to the
  105.       same corresponding parameters    when RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx(((())))
  106.       was called.
  107.  
  108.       dddduuuupppp____ffffuuuunnnncccc(((()))) is    called when a structure    is being copied.
  109.       Pointers to the destination and source CCCCRRRRYYYYPPPPTTTTOOOO____EEEEXXXX____DDDDAAAATTTTAAAA
  110.       structures are passed    in the ttttoooo and ffffrrrroooommmm parameters
  111.       respectively.    The ffffrrrroooommmm____dddd parameter is    passed a pointer to
  112.       the source application data when the function    is called,
  113.       when the function returns the    value is copied    to the
  114.       destination: the application can thus    modify the data
  115.       pointed to by    ffffrrrroooommmm____dddd and have    different values in the    source
  116.       and destination.  The    iiiiddddxxxx, aaaarrrrggggllll and aaaarrrrggggpppp parameters are the
  117.       same as those    in nnnneeeewwww____ffffuuuunnnncccc(((()))) and ffffrrrreeeeeeee____ffffuuuunnnncccc(((()))).
  118.  
  119.      RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  120.       RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx(((()))) returns a new index or    -1 on failure
  121.       (note    0 is a valid index value).
  122.  
  123.       RRRRSSSSAAAA____sssseeeetttt____eeeexxxx____ddddaaaattttaaaa(((()))) returns 1 on success or 0 on failure.
  124.  
  125.       RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____ddddaaaattttaaaa(((()))) returns the    application data or 0 on
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 11/10/00)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx((((3333))))11117777////SSSSeeeepppp////2222000000000000    ((((0000....9999....6666))))RRRRSSSSAAAA____ggggeeeetttt____eeeexxxx____nnnneeeewwww____iiiinnnnddddeeeexxxx((((3333))))
  137.  
  138.  
  139.  
  140.       failure. 0 may also be valid application data    but currently
  141.       it can only fail if given an invalid iiiiddddxxxx parameter.
  142.  
  143.       nnnneeeewwww____ffffuuuunnnncccc(((()))) and dddduuuupppp____ffffuuuunnnncccc(((()))) should return 0 for    failure    and 1
  144.       for success.
  145.  
  146.       On failure an    error code can be obtained from
  147.       ERR_get_error(3).
  148.  
  149.      BBBBUUUUGGGGSSSS
  150.       dddduuuupppp____ffffuuuunnnncccc(((()))) is    currently never    called.
  151.  
  152.       The return value of nnnneeeewwww____ffffuuuunnnncccc(((()))) is ignored.
  153.  
  154.       The nnnneeeewwww____ffffuuuunnnncccc(((()))) function isn't    very useful because no
  155.       meaningful values are    present    in the parent RSA structure
  156.       when it is called.
  157.  
  158.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  159.       rsa(3), CRYPTO_set_ex_data(3)
  160.  
  161.      HHHHIIIISSSSTTTTOOOORRRRYYYY
  162.       _R_S_A__g_e_t__e_x__n_e_w__i_n_d_e_x(), _R_S_A__s_e_t__e_x__d_a_t_a() and
  163.       _R_S_A__g_e_t__e_x__d_a_t_a() are    available since    SSLeay 0.9.0.
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 11/10/00)
  196.  
  197.  
  198.  
  199.